<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
<title>message send</title>
<meta name="generator" content="Amaya, see http://www.w3.org/Amaya/" />
<style type="text/css" title="Amaya theme">
/* Modern style for Amaya Editor Lite */

/* default rules for the whole document */
body {
	font-size: 12pt;
	font-family: Helvetica, Arial, sans-serif;
	font-weight: normal;
	font-style: normal;
	color: black;
	background-color: white;
	line-height: 1.2em;
	margin-left: 2em;
	margin-right: 2em;
}
</style>
</head>

<body>
	<h1>Souliss mini webserver</h1>
	Interact via HTTP /JSON with your souliss network
	<a href="#Interact_via_HTTP_/JSON" class="section_anchor"></a>
	<strong>IMPORTANT NOTE : This is a feature under discussion
		and is not yet available in current release.</strong>
	<p>
		A JSON Server over HTTP is used to expose Souliss data for exernal
		application or user interfaces, using the following HTTP requests and
		a JSON parser you can query the <a href="http://code.google.com/p/souliss/wiki/AndroidApplication">SoulissApp</a> database.
	</p>
	<h3>
		<a name="Structure_HTTP_Request"></a>Structure HTTP Request<a
			href="#Structure_HTTP_Request" class="section_anchor"></a>
	</h3>
	<p>
		At startup, an user interface or an external application can use the
		an <a href="/structure?all"><strong>HTTP GET /structure?all</strong></a> request to have a full
		list of nodes and relevant devices, including their actual state. All
		values are considered as ASCII and can contain either discrete states
		or analog values.
	</p>

	<p>Using a JSON parser this string will be recognized as an array,
		data can be processed as:</p>
	<p></p>
	<table class="wikitable">
		<tbody>
			<tr>
				<td style="border: 1px solid #ccc; padding: 5px;">Description</td>
				<td style="border: 1px solid #ccc; padding: 5px;">Data path</td>
			</tr>
			<tr>
				<td style="border: 1px solid #ccc; padding: 5px;">
					Communication healty for ID n</td>
				<td style="border: 1px solid #ccc; padding: 5px;"><tt>
						json_array.id[n].hlt</tt></td>
			</tr>
			<tr>
				<td style="border: 1px solid #ccc; padding: 5px;">Node
					description ID n</td>
				<td style="border: 1px solid #ccc; padding: 5px;"><tt>
						json_array.id[n].ndesc</tt></td>
			</tr>
			<tr>
				<td style="border: 1px solid #ccc; padding: 5px;">Typical for
					ID n and SLOT m</td>
				<td style="border: 1px solid #ccc; padding: 5px;"><tt>json_array.id[n].slot[m].typ</tt>
				</td>
			</tr>
			<tr>
				<td style="border: 1px solid #ccc; padding: 5px;">Value for ID
					n and SLOT m</td>
				<td style="border: 1px solid #ccc; padding: 5px;"><tt>json_array.id[n].slot[m].val</tt>
				</td>
			</tr>
			<tr>
				<td style="border: 1px solid #ccc; padding: 5px;">Device
					description for ID n and SLOT m</td>
				<td style="border: 1px solid #ccc; padding: 5px;"><tt>json_array.id[n].slot[m].ddesc</tt>
				</td>
			</tr>
		</tbody>
	</table>
	<p></p>
	<p>For each node is available a list of Typicals, that describe
		with a number the device type (light, LED, Air Conditioner, …), the
		user interface shall use an hard-coded mapping between Typicals and
		meaning of value (val) to be used to dynamically setup the user
		interface (available commands and state, description).</p>
	<h2>
		<a name="State_HTTP_Request"></a>State HTTP Request<a
			href="#State_HTTP_Request" class="section_anchor"></a>
	</h2>
	
	<p>
		After the startup, the user interface or an external application shall
		periodically request fresh data in order to show the proper state of
		devices. Using an <a href="/status?all"><strong>HTTP GET /status?all</strong></a> request only
		the live data are passed to the user interface.
	</p>

	<p>Using a JSON parser this string will be recognized as an array,
		data can be processed as:</p>
	<p></p>
	<table class="wikitable">
		<tbody>
			<tr>
				<td style="border: 1px solid #ccc; padding: 5px;">Description</td>
				<td style="border: 1px solid #ccc; padding: 5px;">Data path</td>
			</tr>
			<tr>
				<td style="border: 1px solid #ccc; padding: 5px;">
					Communication healty for ID n</td>
				<td style="border: 1px solid #ccc; padding: 5px;"><tt>
						json_array.id[n].hlt</tt></td>
			</tr>
			<tr>
				<td style="border: 1px solid #ccc; padding: 5px;">Typical for
					ID n and SLOT m</td>
				<td style="border: 1px solid #ccc; padding: 5px;"><tt>json_array.id[n].slot[m].typ</tt>
				</td>
			</tr>
			<tr>
				<td style="border: 1px solid #ccc; padding: 5px;">Value for ID
					n and SLOT m</td>
				<td style="border: 1px solid #ccc; padding: 5px;"><tt>json_array.id[n].slot[m].val</tt>
				</td>
			</tr>
		</tbody>
	</table>
	<p></p>
	<p>
		A request for specific devices can be achieved using instead of <strong>?all</strong>
		parameter the coordinates (id and slot) of the device as <strong>?id=n_id&amp;slot=n_slot</strong>.
	</p>
	
	<h2>
		<a name="Send_Command"></a>Send Command<a href="#Send_Command"
			class="section_anchor"></a>
	</h2>
	<p>For each device the user interface can send command using its
		coordinates (id and slot), followed by one or more value(s). The user
		interface shall use the Typical of the relevant device to list proper
		commands and translate them in an accepted code.</p>
	<p>
		Using <strong>HTTP GET /force?id=0&amp;slot=1&amp;val=01</strong> the
		relevant device will receive a 01 command, the meaning of the command
		is due to the typical assigned to that device. Some devices require
		more than once value as command (for example and RGB LED), in this
		case use concatenation “+” as shown <strong>HTTP GET
			/force?id=0&amp;slot=1&amp;val=22+01+05+01</strong>.
	</p>
	<h2>
		<a name="Device_Mapping" href="/mappings">Device Mapping</a><a href="#Device_Mapping"
			class="section_anchor"></a>
	</h2>
	<p>The user interface or external application need to have an
		hard-coded mapping of typicals and relevant codes (states and
		commands), these are not described in this wiki and are available into
		the !Typicals.h file.</p>
	<p>An example of some states and command code for devices that
		belong to typicals 11, 12 up to 1F are:</p>
	<ul>
		<li>Souliss_T1n_OnCmd, 0x02 // Request to turn device ON</li>
		<li>Souliss_T1n_OffCmd, 0x04 // Request to turn device OFF</li>
		<li>Souliss_T1n_OnCoil, 0x01 // Feedback, device is ON</li>
		<li>Souliss_T1n_OffCoil, 0x00 // Feedback, device is OFF</li>

	</ul>
</body>
</html>
